================================================================================
  CONTEXTO COMPLETO - DASHBOARD FLORESTAL (Três Barras / Westrock)
  Projeto: sag-adm/dashboard_florestal
  Criado em: 24/02/2026
================================================================================

╔══════════════════════════════════════════════════════════════════════════════╗
║  1. OBJETIVO DO PROJETO                                                     ║
╚══════════════════════════════════════════════════════════════════════════════╝

Criar um dashboard PHP/HTML dentro do sistema web "sag-adm" para exibir dados 
de faturamento florestal da operação Três Barras (cliente Westrock/Transpes).

A fonte de dados é a tabela PostgreSQL "public.fttranspes_florestal" no banco 
SAG, que recebe dados de um ETL Python que processa uma planilha Excel de 
viagens florestais (transporte de madeira: fazenda → fábrica).

O dashboard deve:
- Mostrar KPIs do período filtrado (viagens, veículos, faturamento, peso, km)
- Comparar atividade HOJE vs ONTEM (viagens e veículos ativos)
- Ter gráficos de faturamento por veículo e por local/fazenda
- Ranking de veículos e locais
- Tabela detalhada de todas as viagens com paginação (DataTables)
- Filtro de data com atalhos (hoje, ontem, mês atual)
- Exportar CSV
- Seguir o padrão visual do sistema sag-adm (ver seção 5)


╔══════════════════════════════════════════════════════════════════════════════╗
║  2. BANCO DE DADOS                                                          ║
╚══════════════════════════════════════════════════════════════════════════════╝

Servidor:   bi.sagtecnologia.com.br
Porta:      5432
Banco:      SAG
Usuário:    postgres
Senha:      @@Sag@2020
Schema:     public

Banco de log: log (mesma conexão/servidor)

TABELA: public.fttranspes_florestal
────────────────────────────────────
Criada pelo ETL Python. Todas as colunas de dados são TEXT.
Conversão para NUMERIC é feita nas queries (::NUMERIC).

Colunas:
┌────────────────────┬───────────────────────────────────────────────────────┐
│ COLUNA             │ DESCRIÇÃO                                            │
├────────────────────┼───────────────────────────────────────────────────────┤
│ id                 │ SERIAL PRIMARY KEY (auto-increment)                   │
│ seq                │ Sequencial da planilha                                │
│ cliente            │ Nome do cliente                                       │
│ implemento         │ Tipo do implemento (carreta, etc)                     │
│ placa              │ Placa do veículo SEM HÍFEN (ex: RUR7J01)             │
│ motorista          │ Nome do motorista                                     │
│ dtsaidaviagem      │ Data/hora saída p/ viagem (YYYY-MM-DD HH:MM:SS)     │
│ km_saida           │ KM na saída                                          │
│ ordem_coleta_nf    │ Ordem de busca/coleta/NF                             │
│ local              │ Nome do local/fazenda                                 │
│ dmt                │ DMT (distância média transporte)                      │
│ ciclo              │ Ciclo da viagem                                       │
│ dtchegadafazenda   │ Data/hora chegada na fazenda (YYYY-MM-DD HH:MM:SS)  │
│ km_chegada_carreg  │ KM na chegada p/ carregamento                        │
│ qtd_veiculos_fila  │ Qtd veículos na fila                                 │
│ dtiniciocarreg     │ Data/hora início carregamento                         │
│ dtfimcarreg        │ Data/hora fim carregamento                            │
│ dtchegadafabrica   │ Data/hora chegada na fábrica                          │
│ km_chegada_fabrica │ KM na chegada na fábrica                             │
│ peso_liquido       │ Peso líquido (toneladas)                              │
│ dtiniciodescarreg  │ Data/hora início descarregamento                      │
│ dtfimdescarreg     │ Data/hora fim descarregamento                         │
│ dtsaidafabrica     │ Data/hora saída da fábrica/balança                   │
│ km_final           │ KM final                                              │
│ data               │ Data da viagem (apenas data, YYYY-MM-DD)             │
│ faturamento        │ Valor do faturamento (R$)                             │
│ tempo_carreg       │ Tempo de carregamento                                 │
│ tempo_descarreg    │ Tempo de descarregamento                              │
│ tempo_carreg2      │ Tempo de carregamento 2                               │
│ tempo_carreg3      │ Tempo de carregamento 3                               │
│ tempo_carreg4      │ Tempo de carregamento 4                               │
│ soma_km            │ Soma total de KM                                      │
│ dmt_km_produzido   │ DMT KM produzido                                     │
│ dt_carga           │ TIMESTAMP DEFAULT NOW() (data da carga ETL)          │
└────────────────────┴───────────────────────────────────────────────────────┘

UNIQUE INDEX: uq_fttranspes_florestal_placa_dtsaida ON (placa, dtsaidaviagem)
Carga atual: ~150 registros (fevereiro 2026, Westrock)

OBSERVAÇÕES PARA QUERIES:
- As colunas são TEXT, use ::NUMERIC para somar/calcular: faturamento::NUMERIC
- Datas estão como TEXT no formato 'YYYY-MM-DD HH:MM:SS', filtre com:
  DATE(dtsaidaviagem) = '2026-02-20'  ou  DATE(dtsaidaviagem) BETWEEN 'x' AND 'y'
- Placa já vem SEM hífen (tratado no ETL)


╔══════════════════════════════════════════════════════════════════════════════╗
║  3. ESTRUTURA DO PROJETO sag-adm                                            ║
╚══════════════════════════════════════════════════════════════════════════════╝

O sag-adm é um sistema web PHP com a seguinte estrutura:

sag-adm/
├── include/
│   ├── autenticacao.php       ← Validação de sessão (OBRIGATÓRIO no topo)
│   ├── conexaodb.php          ← Cria $bdcon via pg_connect() ao banco SAG
│   ├── inicio.php             ← HTML <head>, CSS vendor, menu, início <body>
│   └── fim.php                ← JS vendor (jQuery, Bootstrap, DataTables...), </body>
├── vendor/
│   ├── bootstrap/css/bootstrap.css
│   ├── jquery/
│   ├── datatables/
│   │   └── media/css/dataTables.bootstrap4.css
│   │   └── i18n/pt-BR.json
│   ├── select2/
│   ├── font-awesome/
│   └── ...
├── css/
│   ├── theme.css
│   ├── custom.css
│   └── skins/default.css
├── js/
│   └── jquery-1.7.2.min.js
├── gt_visaoviagens/           ← Dashboard de referência (foi usado como modelo)
│   ├── index.php
│   └── select.php
├── dashboard_florestal/       ← >>> ESTE PROJETO <<<
│   ├── index.php              ← Dashboard principal (JÁ CRIADO)
│   ├── select.php             ← Queries PostgreSQL (JÁ CRIADO)
│   ├── export.php             ← Exportação CSV (JÁ CRIADO)
│   └── CONTEXTO_PROJETO.txt   ← Este arquivo
└── DOCUMENTACAO_PADROES/
    └── SNIPPETS_CODIGO_PADRAO.md


╔══════════════════════════════════════════════════════════════════════════════╗
║  4. PADRÃO DE CÓDIGO DO SISTEMA sag-adm                                    ║
╚══════════════════════════════════════════════════════════════════════════════╝

4.1 ESTRUTURA DE PÁGINA PHP (OBRIGATÓRIO):
─────────────────────────────────────────
Todo módulo segue este padrão:

  select.php  → Contém as queries SQL e variáveis PHP
  index.php   → Contém o HTML e inclui select.php + inicio.php + fim.php

Exemplo index.php:
  <?php
  $grupotitulo  = 'NOME_GRUPO';
  $rotinatitulo = 'Título da Rotina';
  include('select.php');
  include('../include/inicio.php');
  ?>
  <!-- HTML aqui -->
  <?php include('../include/fim.php'); ?>

Exemplo select.php:
  <?php
  require('../include/autenticacao.php');
  $codempresa = $_SESSION['codempresa'];
  // queries aqui usando pg_query($bdcon, $sql);
  // $bdcon já disponível via conexaodb.php (incluído por inicio.php)
  ?>

4.2 CONEXÃO COM O BANCO:
─────────────────────────
A conexão $bdcon é criada em include/conexaodb.php e fica disponível globalmente.
Usa pg_connect() do PHP (extensão PostgreSQL nativa).

Queries:
  $sql = "SELECT * FROM tabela WHERE coluna = '$variavel'";
  $res = pg_query($bdcon, $sql);
  while($row = pg_fetch_assoc($res)) { ... }
  // ou pg_fetch_array($res) para array misto

4.3 SESSÃO:
───────────
Variáveis disponíveis após autenticacao.php:
  $_SESSION['codempresa']     → ID da empresa (int)
  $_SESSION['grupousuario']   → ID do grupo de permissão
  $_SESSION['UsuarioID']      → ID do usuário logado
  $_SESSION['empresa']        → Nome da empresa

4.4 VENDOR (JS/CSS) JÁ INCLUÍDOS POR inicio.php / fim.php:
────────────────────────────────────────────────────────────
CSS (via inicio.php):
  - Bootstrap 4 (../vendor/bootstrap/css/bootstrap.css)
  - Material Icons (Google Fonts)
  - Font Awesome
  - DataTables (../vendor/datatables/media/css/dataTables.bootstrap4.css)
  - Select2 (../vendor/select2/css/select2.css)
  - jQuery UI
  - PNotify

JS (via fim.php):
  - jQuery (jquery-1.7.2.min.js + vendor moderno)
  - Bootstrap JS
  - DataTables JS + Buttons (CSV, Excel, PDF, Print, ColVis)
  - Select2
  - jQuery Mask Plugin
  - Bootstrap Datepicker
  - PNotify

4.5 LAYOUT HTML:
────────────────
Estrutura padrão do conteúdo dentro do template:

  <div class="inner-wrapper">
  <div class="content-body">
    <ol class="breadcrumbs">
      <li class="breadcrumb-item home"><a href="../dashboard/index.php"><i class="material-icons">home</i></a></li>
      <li class="breadcrumb-item"><span>Grupo</span></li>
      <li class="breadcrumb-item active"><span>Rotina</span></li>
    </ol>
    <!-- conteúdo aqui -->
  </div>
  </div>

4.6 CLASSE DE TABELA PADRÃO:
─────────────────────────────
  class="table table-hover table-sm"
  DataTables: id="tbl_xxx" com inicialização em $(document).ready()

4.7 ÍCONES:
────────────
  Material Icons: <span class="material-icons">nome_icone</span>
  Font Awesome:   <i class="fas fa-xxx"></i>


╔══════════════════════════════════════════════════════════════════════════════╗
║  5. ESTILO VISUAL DO DASHBOARD FLORESTAL                                    ║
╚══════════════════════════════════════════════════════════════════════════════╝

O dashboard usa classes CSS próprias com prefixo "fl-" (florestal):

5.1 SEÇÕES COM CABEÇALHO ESCURO:
  .fl-section-header → linear-gradient 0f172a → 1e293b → 334155
  Ícone em Material Icons com cor #7dd3fc
  Texto branco, bold, uppercase

5.2 KPI CARDS (.fl-kpi):
  Background branco, border-radius 12px, shadow leve
  border-left 4px com cor temática:
    - padrão (azul): #0ea5e9
    - .verde:  #22c55e
    - .laranja: #f97316
    - .roxo:   #a855f7
    - .cinza:  #94a3b8
  
  Estrutura interna:
    .kpi-label → texto superior pequeno (11px, uppercase, cinza)
    .kpi-value → valor principal (22px, bold, escuro)
    .kpi-sub   → subtexto descritivo (11px, cinza claro)
    .kpi-icon-bg → ícone grande de fundo (54px, opacity 5%)

5.3 GRID ATIVIDADE HOJE/ONTEM:
  .fl-atividade-grid → grid 2 colunas
  .fl-atv-card.hoje  → header azul (#0ea5e9)
  .fl-atv-card.ontem → header cinza (#64748b)
  .fl-atv-table      → tabela compacta com placa-badge (fundo escuro, mono)

5.4 GRÁFICOS:
  Chart.js v3.9.1 (CDN)
  .fl-chart-box → container branco com shadow
  Paleta de cores: #0ea5e9, #22c55e, #f97316, #a855f7, #f43f5e, etc.

5.5 FILTRO DE DATA:
  .fl-filter-bar → barra branca com borda, inputs date + botões
  .btn-filtrar → azul #0ea5e9
  .btn-hoje → cinza claro com borda
  Atalhos JS: setHoje(), setOntem(), setMes()


╔══════════════════════════════════════════════════════════════════════════════╗
║  6. ARQUIVOS JÁ CRIADOS E SEUS CONTEÚDOS                                   ║
╚══════════════════════════════════════════════════════════════════════════════╝

6.1 select.php (193 linhas)
─────────────────────────────
Contém TODAS as queries SQL:
  - $kpi_hoje       → KPIs do dia atual (viagens, veículos, fat, peso, km, dmt)
  - $kpi_ontem      → KPIs do dia anterior
  - $kpi_periodo    → KPIs do período filtrado (inclui fat_por_km)
  - $veiculos_hoje  → Array de viagens de hoje (placa, motorista, local, fat...)
  - $veiculos_ontem → Array de viagens de ontem
  - $viagens        → Array completo do período (24 colunas, para tabela detalhada)
  - $por_veiculo    → GROUP BY placa com SUM(fat), SUM(peso), SUM(km), AVG(dmt)
  - $por_local      → GROUP BY local, top 10 por faturamento

Filtros:
  - $dtinicio e $dtfim via GET (default: hoje)
  - Sanitização com preg_replace

Helpers:
  - fmt_moeda($v)    → "R$ 1.234,56"
  - fmt_num($v, $d)  → "1.234" ou "1.234,5"
  - fmt_data($d)     → "20/02/2026 14:30"
  - var_pct($h, $o)  → "▲ 15.3%" (verde) ou "▼ 8.2%" (vermelho)

6.2 index.php (565 linhas)
─────────────────────────────
Dashboard principal com:
  - CSS próprio (classes fl-*)
  - Filtro de período com date pickers + botões atalho
  - 7 KPI cards do período (viagens, veículos, fat, peso, km, dmt, fat/km)
  - 4 KPI cards hoje vs ontem (com variação %)
  - Grid 2 colunas: atividade HOJE e ONTEM (tabelas com placa-badge)
  - 2 gráficos Chart.js (fat por veículo barras + top locais horizontal)
  - Ranking por veículo (tabela DataTables sem paginação)
  - Ranking por local/fazenda
  - Tabela detalhada de viagens com 14 colunas + DataTables + paginação 25
  - Botão "Exportar CSV" no cabeçalho
  - Scripts JS: Chart.js CDN + DataTables init + funções de atalho de data

6.3 export.php (53 linhas)
─────────────────────────────
Endpoint para download CSV:
  - Filtra por dtinicio/dtfim via GET
  - Gera CSV com separador ";" e BOM UTF-8 (compatível Excel)
  - Nome do arquivo: florestal_YYYYMMDD_YYYYMMDD.csv
  - 28 colunas exportadas


╔══════════════════════════════════════════════════════════════════════════════╗
║  7. STATUS ATUAL E O QUE FALTA FAZER                                       ║
╚══════════════════════════════════════════════════════════════════════════════╝

✅ FEITO:
  - select.php (queries completas)
  - index.php (dashboard completo com KPIs, tabelas, gráficos)
  - export.php (CSV)
  - ETL Python rodando (python_etl/transpes/faturamento_florestal/)
  - 150 registros carregados no banco

🔲 POSSÍVEIS MELHORIAS / PENDÊNCIAS:
  1. TESTAR no navegador e ajustar qualquer erro visual ou de query
  2. Adicionar gráfico de faturamento por DIA (linha do tempo)
  3. Adicionar indicadores de META (FAT META vs FAT REAL, se houver dados)
  4. Adicionar cálculo de dias produtivos (dias com >= 1 viagem)
  5. Verificar se precisa filtrar por $_SESSION['codempresa'] 
     (atualmente NÃO filtra, pois os dados são só da Transpes)
  6. Registrar a rotina na tabela sis_rotina do sistema para aparecer no menu
  7. Ajustar responsividade mobile se necessário
  8. Considerar AJAX para atualização sem reload (opcional)
  9. Adicionar permissões via sis_permissaogrupo


╔══════════════════════════════════════════════════════════════════════════════╗
║  8. ETL PYTHON (REFERÊNCIA)                                                 ║
╚══════════════════════════════════════════════════════════════════════════════╝

Localização: sagetl/python_etl/transpes/faturamento_florestal/

Arquivos:
  - config.py       → Conexão BD, COLUMN_MAP (32 colunas Excel → nomes curtos)
  - main.py         → Pipeline: extract → transform → create_table → load
  - requirements.txt → psycopg2-binary, pandas, openpyxl, setproctitle
  - run.bat         → Script de execução Windows

Funcionamento:
  1. Lê Excel (aba "VIAGENS") com pandas + openpyxl
  2. Aplica COLUMN_MAP (renomeia colunas do Excel para nomes do banco)
  3. Converte 9 colunas de data para "YYYY-MM-DD HH:MM:SS"
  4. Remove hífens da placa (RUR-7J01 → RUR7J01)
  5. Converte tudo para TEXT
  6. CREATE TABLE IF NOT EXISTS + UNIQUE INDEX on (placa, dtsaidaviagem)
  7. INSERT com ON CONFLICT DO NOTHING (evita duplicatas)
  8. Registra execução no banco de log

CLI:
  python main.py                 → Carga completa (truncate + insert)
  python main.py --append        → Apenas insere sem truncar
  python main.py --preview       → Mostra preview sem inserir
  python main.py --arquivo X.xlsx → Usa arquivo específico


╔══════════════════════════════════════════════════════════════════════════════╗
║  9. REFERÊNCIA: DASHBOARD gt_visaoviagens (MODELO VISUAL)                   ║
╚══════════════════════════════════════════════════════════════════════════════╝

O dashboard_florestal foi inspirado no gt_visaoviagens, que usa:
  - Classes CSS com prefixo .vg- (ex: .vg-kpi, .vg-scroll, .vg-section-toggle)
  - Stage timeline (etapas da viagem com ícones)
  - Event timeline (eventos em lista vertical)
  - KPI cards com ícone de fundo grande (opacity baixa)
  - Cabeçalho dark gradient (mesmas cores usadas no florestal)
  - Filtros no topo da página

O florestal adaptou esse padrão com classes .fl-* e adicionou:
  - Gráficos Chart.js (o visaoviagens não tinha)
  - Grid comparativo hoje/ontem
  - Rankings por veículo e local
  - Exportação CSV


╔══════════════════════════════════════════════════════════════════════════════╗
║  10. QUERIES SQL ÚTEIS (COPIAR E COLAR)                                     ║
╚══════════════════════════════════════════════════════════════════════════════╝

-- Ver todos os dados
SELECT * FROM public.fttranspes_florestal ORDER BY id;

-- Resumo por placa
SELECT placa, COUNT(*) AS viagens, 
       SUM(faturamento::NUMERIC) AS fat_total,
       SUM(peso_liquido::NUMERIC) AS peso_total,
       SUM(soma_km::NUMERIC) AS km_total
FROM public.fttranspes_florestal
GROUP BY placa ORDER BY fat_total DESC;

-- Resumo por data
SELECT DATE(dtsaidaviagem) AS dia, COUNT(*) AS viagens,
       SUM(faturamento::NUMERIC) AS fat
FROM public.fttranspes_florestal
WHERE dtsaidaviagem IS NOT NULL
GROUP BY DATE(dtsaidaviagem) ORDER BY dia;

-- Veículos ativos hoje
SELECT DISTINCT placa, motorista
FROM public.fttranspes_florestal
WHERE DATE(dtsaidaviagem) = CURRENT_DATE;

-- Estrutura da tabela
SELECT column_name, data_type 
FROM information_schema.columns 
WHERE table_name = 'fttranspes_florestal' 
ORDER BY ordinal_position;


╔══════════════════════════════════════════════════════════════════════════════╗
║  11. COMO TESTAR                                                            ║
╚══════════════════════════════════════════════════════════════════════════════╝

1. O projeto sag-adm roda em um servidor web com PHP + extensão pg_connect
2. Acessar via navegador: http://<servidor>/dashboard_florestal/index.php
3. Precisa estar logado no sistema (sessão ativa)
4. Os dados estão em fevereiro 2026, então use o filtro de datas:
   dtinicio=2026-02-01 e dtfim=2026-02-28 para ver todos os 150 registros
5. O filtro padrão é "hoje" — se não houver dados de hoje, os KPIs ficam zerados
   (isso é esperado)


================================================================================
  FIM DO DOCUMENTO DE CONTEXTO
  Para qualquer IA que for dar continuidade: leia este arquivo inteiro,
  depois leia os 3 arquivos PHP (select.php, index.php, export.php) e 
  faça os ajustes/melhorias solicitados pelo usuário.
================================================================================
